CreateThread

CreateThread creates a thread to execute within the address space of the calling process.

Syntax

HANDLE CreateThread(
    LPSECURITY_ATTRIBUTES lpThreadAttributes,
    DWORD StackSize,
    LPTHREAD_START_ROUTINE lpStartAddress,
    LPVOID lpParameter,
    DWORD dwCreationFlags,
    LPDWORD lpThreadId
);

Parameters

lpThreadAttributes

Ignored. A pointer to a SECURITY_ATTRIBUTES structure that determines whether the returned handle can be inherited by child processes. If lpThreadAttributes is NULL, the handle cannot be inherited.

StackSize

The size, in bytes, of the stack for the new thread. If 0 is specified, the stack size defaults to 8192 bytes under RTSS or to the same size as the calling thread's stack under Win32. The stack is allocated automatically in the memory space of the process, and it is freed when the thread terminates. In the Win32 environment, the stack size grows when necessary. In the RTSS environment, the stack cannot grow.

The number of bytes specified by StackSize must be available from non-paged memory in the kernel.

lpStartAddress

A pointer to the application-supplied function to be executed by the thread and represents the starting address of the thread. The function accepts a single 32-bit argument and returns a 32-bit exit value.

lpParameter

A single 32-bit parameter value passed to the thread.

CreationFlags

Additional flags that control the creation of the thread. If the CREATE_SUSPENDED flag is specified, the thread is created in a suspended state and will not run until ResumeThread is called. If this value is zero, the thread runs immediately after creation. At this time, no other values are supported.

lpThreadId

A pointer to a 32-bit variable that receives the thread identifier.

Return Values

A handle to the new thread if the function succeeds, NULL if the function fails

To get extended error information, call GetLastError.

Remarks

The new thread handle is created with full access to the new thread.

The thread execution begins at the function specified by lpStartAddress. If this function returns, the DWORD return value is used to terminate the thread in an implicit call to ExitThread.

The thread is created with a thread priority of 0. Use GetThreadPriority and SetThreadPriority to get and set the priority value of a thread.

The thread object remains in the system until the thread has terminated and all handles to it have been closed through a call to CloseHandle. (For threads, use CloseHandle rather than RtCloseHandle.)

ExitProcess, ExitThread, and CreateThread, as well as a process that is starting, are serialized between each other within a process. Only one of these events can happen in an address space at a time.

A small memory leak (approximately 1040 bytes per thread) occurs in the C Runtime library when CreateThread and ExitThread are used instead of _beginthreadex and _endthreadex to create and terminate real-time threads. For more information, see the Microsoft support article at https://support.microsoft.com/en-us/kb/104641. Note that the Stack space for a real-time thread is not freed until all handles to the thread have been closed.

Requirements

Library

Rtx_Rtss.lib